SGI Developer Toolbox 6.1/SGI Developer Toolbox 6.1 - Disc 4.iso/src/demos/GL/buttonfly/README

Text File | 1994-08-01 | 8KB | 166 lines

                      toolbox/src/demos/GL/buttonfly README

     Buttonfly is a hierarchical, graphical menu system.  It provides a
     simple-to-use graphical interface for launching applications.

     Buttonfly uses a hiercharical menu structure which is designed to
     be easily configurable.  What follow is a liberal extract from the
     buttonfly(6D) man page on how to configure Buttonfly to better
     customize it to fit your needs.

     To run an example, execute the "buttonfly.sh" script.  See the files
     in the "menus" directory for more info.


RECONFIGURING BUTTONFLY

     Buttonfly's menus were designed to be simple to change with any UNIX
     text editor (such as vi ).  When it is run with no arguments, it looks
     for button descriptions in a file called '.menu' in the current
     directory.  If it is given one argument, it will look in that file
     for button definitions instead.

     Buttonfly uses a very simple format to describe its buttons.  The
     format has four different kinds of lines: comments, titles, actions,
     and commands.

     Any line beginning with a '#' character is considered a comment and is
     ignored.

     Button titles, like comments, always start in the first column of the
     file, and may be anything not starting with a '#'.  Titles may be a
     maximum of 36 characters long; buttonfly will automatically separate the
     title into a maximum of three lines of twelve characters, separating
     words in the title at spaces.

     Action lines start with a tab and end with a newline, and may be any
     UNIX command.  Multiple actions may be specified for a button by listing
     them after the button one per line, each starting with a tab.  Actions
     may not span more than one line, but may be any length.  If no actions
     are speci- fied for a button, the button is displayed, but nothing will
     happen when it is selected.

     Commands, like actions, start with a tab character.  Currently, the
     commands recognized are '.menu.', '.popup.', '.cd.', '.color.',
     '.backcolor.', and '.highcolor.'.  Everything else is assumed to be an
     action and will be executed as a UNIX command in a shell (see sh(1)).

     The special action called '.menu.' is used to specify a button that has
     several buttons attached to the back of it.  When buttonfly sees '.menu.
     filename' it will create a new set of buttons from the descriptions in
     'filename'.  If it cannot find 'filename' in the current directory, then
     nothing happens.  If 'filename' is '-', then the new set of buttons is
     created from the standard output of the previous actions (see example
     below).  Note that any 'cd' commands in an action list do not affect the
     directory in which buttonfly looks for the filenames specified in
     '.menu.' commands, becuase actions are executed in a sub-shell (see the
     '.cd.' command below).

     Another special actions is '.popup.'.  It is used to define a pop-up
     menu entry attached to a button.  When buttonfly sees '.popop. title'
     it adds an entry 'title' to the button's pop-up menu.  The actions
     following a .popup. command will be executed when that menu entry is
     chosen.  Buttonfly automatically provides a 'Do It' entry, which has
     the same effect as pressing the left mouse button.

     The '.cd.' action is used to change buttonfly's idea of the current
     working directory.  When the button containing the .cd. command is
     pressed, buttonfly will chdir into that directory before executing
     that button's actions, and all buttons underneath that button will
     also be executed in that directory (unless they also have .cd. commands).
     Note that executing the regular 'cd' shell command in a button does not
     affect buttonfly's idea of the current working directory, since all
     button actions are executed in their own shell environment.

     The command '.color.' followed by three numbers in the range 0.0 ... 1.0
     specifies the red, green and blue components of a button's color, and
     '.highcolor' does the same for the color of the button as it is being
     selected.  '.backcolor.' changes the color of the back of the button,
     which becomes the background color of the next set of buttons (displayed
     when the button flips over).  Note that using color commands at the top
     of a file, before any buttons have been defined, causes the default
     colors to be changed for all subsequent buttons.  To change the
     background color to red for the first button and all subsequent
     buttons you would specify:

          .backcolor. 1.0 0.0 0.0

     in the menu description file before any buttons are defined.

EXAMPLES

     The following are example buttonfly .menu files, with descriptions of
     what they do.

     This is a very simple button called 'First' that has the buttons defined
     in the file '.menu_second' on the back of it.

          First
               .menu. .menu_second

     Here are three buttons.  The 'Parent' button is purple and will flip
     over and display the other two buttons when pressed (they will be
     displayed on a purple background, since that is the color on the back
     of the first button).  The 'Demonstrate...' button changes directories
     and then runs a program when pressed, and 'Recurse' flips over and shows
     the first button again, this time on a blue background since the
     '.backcolor.' command changes the background color to blue.

          #Save this in a file called '.menu'
          Parent
               .color. .89 .10 .89
               .backcolor. .89 .10 .89
               .highcolor. 1.0 .5 1.0
               .menu. child

          #Save the following buttons in a file called 'child'
          Demonstrate GL/NeWS Interface
               cd /usr/NeWS/demo
               glnews
          Recurse
               .backcolor. 0.0 0.0 1.0
               .menu. .menu

     Here is a very complicated button, which builds a button file based
     on the files it finds in a directory full of files.  When pressed,
     it builds the file and then uses .menu.  to flip over, exposing entries
     for all the files it found.  Note that this allows you to delete or add
     image files, and the buttons will always be accurate.  It also has a
     pop-up menu on it giving help; the first .popup command specifies the
     title of the menu using the %t feature of Silicon Graphics menus.

          Show An Image
               cd /usr/demos/data/images
          #The following two lines must all be on the
          # same line in the .menu file
               /bin/ls *.rgb | awk 'BEGIN{FS="."}{print "Show " $1
          "\n\tipaste /usr/demos/data/images/" $0 "\n"}'
               .menu. -
               .popup. ShowImage Menu %t
               .popup. Ipaste Man Page
               wsh -c man ipaste

BUGS

     Buttonfly will not work if the first character of a file is a TAB
     followed by anything other than .color., .backcolor., or .highcolor.
     It is safest to eliminate any blank lines from the files you create.

     Buttonfly may crash if given an arbitrary file as input.

     The maximum number of buttons on any level of the hierarchy is 32.

     If a program fails to run, nothing happens-- no error messages or
     warnings are given.  This can be considered either a feature or a bug.

     Specifying %F, %f, %x, or %m as part of a .popup. title will give bad
     results, and may crash the program.  Using %t to specify a title works,
     but any actions specified for that entry will never be executed (since
     it is impossible to select a title entry).

FILES

     /usr/demos/.m* are the button files the demos use.